Skip to main content

Quick start

The documentation describes the algorithm for connecting the DXChart library for the iOS with basic functionality.

Requirements​

  • iOS 15.0+
  • Real device or simulator to launch the app

Demo project​

We provide a demo project with all default providers (based on DXFeedFramework) and default settings upon client request.

Installation​

To install this package locally, follow these steps:

  1. Unzip the package:
   unzip DXPackage.zip -d <destination_path>

  1. Open your project in Xcode.

  2. Add the local package:

    • Go to File -> Add Packages...
    • Click on Add Local...
    • Navigate to the unzipped folder "DXPackage" and select it.

  3. Ensure the package is added to your target's dependencies.

Base framework configuration​

For prepare framework for work do this steps:

  1. Import the DXChart module in your UIApplicationDelegate.
import DXChart
  1. Configure framework used a method configure() of DXChartApp in your app delegate's application(_:didFinishLaunchingWithOprions:) method:
DXChartApp.configure()

That's it! You can see an example about setup custom configuration

Using the Chart​

Describe components​

You can use ChartView and ChartScreen components to present your data.

  • ChartView is a UIView component that you can integrate into your screens. It has an API for configuration and displaying data directly. (This component is available starting from version 1.2.0.")

  • ChartScreen is the UIViewController that includes all features of our framework. It requires some dependencies to work, such as CandlesProvider and IPFDataProvider. It encapsulates a huge part of the logic related to the chart and has more features than ChartView.

Using ChartScreen​

This section describes how to integrate ChartScreen directly into your iOS application.

You can provide Candle data to ChartScreen to display on the chart used CandlesProvider. If you need a service to retrieve market data, you can use DXFeedFramework.

The settings parameters are set to default values and persist changes during usage. To store and manage settings, ChartScreen uses a SettingsManager. You can provide your own instance of the manager or use the default implementation (DXCSettingsManager). To set up custom parameters, see Settings.

Chart screen configuration​

To configure ChartScreen, you need to initialise it using the static method makeScreen() from ChartScreen enum. A ChartScreen instance requires the following mandatory dependencies:

  • dataProvider - provides all the necessary data for the chart..
  • delegate - a delegate for handling trading operations (buy/sell).
  • shouldShowLogo - the flag to control whether the logo should be displayed on the chart (if provided).
  • dataStorage - a storage system for managing instrument and aggregation data.
  • settingsManager - a manager for handling chart settings
  • uniqueIdentifier - a unique identifier to differentiate contexts when using multiple charts simultaneously. (Required only if you need to display multiple charts with different data.)

You can provide your custom provider or implement by example if you use DXFeedFramework. To setting up default data providers see Configuration There is interface for making UIViewController of ChartScreen:

public enum ChartScreen {
  public static func makeScreen(
      dataProvider: DataProvider,
      delegate: QuoteOperationsDelegate,
      logoImage: UIImage?,
      shouldShowLogo: Bool,
      shouldShowToolbar: Bool = true,
      dataStorage: DataStorage = DXChartApp.dataStorage,
      settingsManager: SettingsManager = DXChartApp.settingsManager,
      uniqueIdentifier: String? = nil
  )
}

DataProvider​

To provide data to the chart, you need to implement a DataProvider that conforms to the DXChart.DataProvider protocol. You can use the default implementation built on DXFeed, which is available here.

public protocol DataProvider {
  var candlesProvider: CandlesProvider { get }
  var quotesDataProvider: QuotesDataProvider { get }
  var ipfDataProvider: IPFDataProvider { get }
  var scheduleProvider: ScheduleProvider { get }
  var newsProvider: NewsProvider? { get }
  var studiesProvider: StudiesProvider { get }
}

CandlesProvider​

CandlesProvider — provides data with selected trading instrument's candles that needs to be displayed on the chart. You can use the default implementation built on DXFeed, which is available here.

import Combine
/// Protocol for receiving candle data and managing the state of the connection.
///
/// Provider that supplies data about candles for the selected trading instrument. The chart listens to `candlesPublisher`,
/// a flow of candle data updates, and reacts to changes in it by updating the displayed information accordingly.
/// Whenever there is a new candle data emitted by `candlesPublisher`, the chart updates to reflect this new data,
/// ensuring that the visual representation of the trading instrument's price movements is always current and accurate.
public protocol CandlesProvider {
  /// Publisher for receiving an array of `Candle` data.
  ///
  /// Provides the publisher of candle data for the requested symbol.
  var candlesPublisher: AnyPublisher<[Candle], Never> { get }
  /// Publisher for receiving the availability state of candle data.
  ///
  /// Emits `true` when data is available, `false` otherwise.
  var isDataAvailable: AnyPublisher<Bool, Never> { get }
  /// Publisher for receiving the loading state of candle data after parameters change.
  ///
  /// Emits `true` when candle data is being loaded, `false` when loading is complete.
  var isLoading: AnyPublisher<Bool, Never> { get }
  /// Publisher for receiving the current connection state.
  ///
  /// Tracks the state of the connection to the candle data provider.
  var connectionState: AnyPublisher<DXChart.ConnectionState, Never> { get }
  /// Updates the parameters for receiving candle data.
  ///
  /// - Parameters:
  ///   - symbol: The instrument symbol for which the candle data is requested.
  ///   - priceType: The type of price to use for the instrument (bid, ask, last, market).
  ///   - aggregation: The aggregation settings for the candle data (time interval or granularity).
  ///   - extendedHours: Flag indicating whether to include extended trading hours in the data.
  ///   - alignSessionStart: Flag indicating whether to align data to the start of the trading session.
  func changeParams(
      symbol: String,
      priceType: PriceType,
      aggregation: Aggregation,
      extendedHours: Bool,
      alignSessionStart: Bool
  )
}

QuotesDataProvider​

QuotesDataProvider — provides data with selected trading instrument's quotes for the selected instrument, including Bid and Ask prices. You can use the default implementation built on DXFeed, which is available here.

import Combine
/// Interface for receiving quotes data used in the DXChart framework.
///
/// When loading a chart in the DXChart framework, quotes data is sourced from this interface.
///
/// - Use `dataPublisher` to supply quotes data.
/// - Use `changeSymbol` to change the instrument symbol for which quotes are being provided.
public protocol QuotesDataProvider {
  /// Publisher that provides quotes data.
  ///
  /// The quotes data is represented by the `Quote` structure. This publisher emits the latest `Quote` data, and a `nil` value if no data is available.
  var dataPublisher: AnyPublisher<Quote?, Never> { get }
  /// Changes the instrument symbol for which quotes are being provided.
  ///
  /// - Parameter symbol: The instrument symbol (e.g., "AAPL", "TSLA") for which the quotes data should be fetched.
  func changeSymbol(_ symbol: String)
}

IPFDataProvider​

IPF Data Provider - provides the list of symbols which user can select to see on the chart. DataProvider also should store IPF data provider which conform IPFDataProvider protocol. You can use the default implementation built on DXFeed, which is available here.

import Combine
/// Protocol for receiving instrument profile data - array of InstrumentData.
///
/// When loading DXChart framework, an array of instruments, their descriptions, etc. are taken from this interface
///
/// When connecting DXChart framework, developer can implement this interface or use the default implementation [link on the default implementation] and pass it to the framework using DXChart.DataProvider class
public protocol IPFDataProvider {
  /// Publisher of receiving instrument profile data.
  ///
  /// Instrument profile data is represented by array of InstrumentData.
  var dataPublisher: AnyPublisher<Result<[DXChart.Instrument], Error>, Never> { get }
  /// Provide information about loading status.
  var isLoading: AnyPublisher<Bool, Never> { get }
}

ScheduleProvider​

DataProvider also should store Schedule data provider which conform ScheduleProtocol protocol. ScheduleProvider - provides schedule for Extended Hours and Session Breaks. You can use the default implementation built on DXFeed, which is available here

  /// A protocol that provides session breaks and extended hours data for the chart.
  ///
  /// The `ScheduleProvider` is responsible for supplying trading session breaks and extended hours information,
  /// which are used to highlight specific time ranges on the chart (e.g., market open/close times, breaks, or after-hours trading).
  ///
  /// When integrating with `DXFeedFramework`, developers can either implement this protocol themselves or use the default implementation
  /// provided by the library. The provider is passed to the library via the `DataProviders` class.
  /// You can find Default Implementation Documentation here https://devexperts.com/dxcharts/documentation-for-developers/Chart%20for%20iOS
  ///
  /// - Note: Proper implementation of this protocol ensures accurate visualization of trading sessions and extended hours on the chart.
  public protocol ScheduleProvider {
      /// Fetches the complete trading schedule for a specific instrument within a given time range.
      ///
      /// This method retrieves the full trading schedule, including session breaks and extended hours, for a specific instrument.
      /// The data is returned as a `Trading.Schedule` object, which provides detailed information about trading sessions.
      ///
      /// - Parameters:
      ///   - startTime: The start time of the requested range, in milliseconds since the Unix epoch.
      ///   - endTime: The end time of the requested range, in milliseconds since the Unix epoch.
      ///   - instrument: The financial instrument for which the trading schedule is requested.
      ///   - completion: A closure that is called with the result of the operation. The result contains either a `Trading.Schedule` or an `Error` if the request fails.
      func fetchTradingSchedule(
          startTime: Int64,
          endTime: Int64,
          instrument: Instrument,
          completion: @escaping (Result<Trading.Schedule, Error>) -> Void
      )
  }

NewsProvider​

NewsProvider responsible for news and events on chart. You should provide your custom network manager which should confirm NewsProvider protocol. Otherwise news and events wouldn't show on chart. Make your custom new provider which conform "NewsProvider protocol". You can provide your custom provider or implement by example if you use DXFeedFramework. You can use the default implementation built on DXFeed, which is available here

import Combine
/// A protocol for providing news data related to a specific financial instrument.
///
/// The `NewsProvider` protocol defines the required functionalities for any provider that supplies
/// news data, corporate actions, conference call information, and earnings data for a presented symbol.
/// Conforming types must implement the necessary publishers to push relevant data updates.
///
/// This protocol is useful for applications that need to display timely news and corporate information
/// to users based on the selected financial instrument.
public protocol NewsProvider {
  /// A publisher that emits an array of `NewsItem` instances related to the presented symbol.
  ///
  /// The publisher sends updates as a result of fetching news data, providing either
  /// a success case containing an array of news items or an error case if the request fails.
  var newsPublisher: AnyPublisher<Result<[DXChart.NewsItem], Error>, Never> { get }
  /// A publisher that emits an array of `CorporateAction` instances.
  ///
  /// This publisher sends updates on corporate actions (e.g., stock splits, dividends) relevant to
  /// the presented symbol, similar to the `newsPublisher` in structure and functionality.
  var corporateActionPublisher: AnyPublisher<Result<[DXChart.CorporateAction], Error>, Never> { get }
  /// A publisher that emits an array of `Earning` instances related to conference calls.
  ///
  /// This publisher provides information about upcoming and past conference calls for the
  /// presented symbol, allowing consumers to stay informed about earnings announcements.
  var conferenceCallPublisher: AnyPublisher<Result<[DXChart.Earning], Error>, Never> { get }
  /// A publisher that emits an array of `Earning` instances related to earnings reports.
  ///
  /// This publisher sends updates on earnings data for the symbol, helping consumers track performance
  /// and financial metrics associated with the instrument.
  var earningsPublisher: AnyPublisher<Result<[DXChart.Earning], Error>, Never> { get }
  /// Updates the data for the specified financial instrument symbol.
  ///
  /// - Parameter symbol: The symbol for which to fetch and update news data.
  /// This method should be called whenever the user selects a different symbol to display
  /// its associated news and corporate actions.
  func updateData(for symbol: String)
}

StudiesProvider​

DataProvider also should store Studies (indicators) data provider which conform StudiesProvider protocol. StudiesProvider - provides studies calculated data for current displayed data on the chart.

/// A protocol defining the methods required to manage studies (indicators) for a chart.
///
/// A `StudiesProvider` is responsible for creating, updating, and removing studies (e.g., technical indicators)
/// based on the provided settings and candle data. It is typically used in conjunction with a chart to dynamically
/// calculate and display indicators such as moving averages, Bollinger Bands, MACD, etc.
public protocol StudiesProvider {
  /// Creates studies (indicators) based on the provided settings and candle data.
  ///
  /// This method calculates the studies (e.g., technical indicators) using the provided `indicators` settings
  /// and `candles` data. The calculated studies are returned via the `completion` handler.
  ///
  /// - Parameters:
  ///   - indicators: An array of `Indicator` objects defining the studies to be calculated.
  ///   - candles: An array of `Candle` objects representing the historical data used for calculations.
  ///   - schedule: An optional `Trading.Schedule` object representing the trading schedule. This can be used
  ///              to adjust calculations based on market hours.
  ///   - completion: A closure that is called with the calculated studies as an array of `StudyData` objects.
  func makeStudies(
      indicators: [Indicator],
      candles: [Candle],
      schedule: Trading.Schedule?,
      completion: @escaping ([StudyData]) -> Void
  )
  /// Updates existing studies with new candle data or settings.
  ///
  /// This method recalculates the studies based on the provided `indicators` settings and optionally
  /// new `candles` data. The updated studies are returned via the `completion` handler.
  ///
  /// - Parameters:
  ///   - indicators: An array of `Indicator` objects defining the studies to be updated.
  ///   - newCandles: An optional array of `Candle` objects representing new or updated historical data.
  ///   - schedule: An optional `Trading.Schedule` object representing the trading schedule.
  ///   - completion: A closure that is called with the updated studies as an array of `StudyData` objects.
  func updateStudy(
      indicators: [Indicator],
      newCandles: [Candle]?,
      schedule: Trading.Schedule?,
      completion: @escaping ([StudyData]) -> Void
  )
  /// Notifies the provider that studies (indicators) are no longer needed and can be cleaned up.
  ///
  /// This method informs the provider that the studies are no longer required, allowing it to release
  /// any associated resources or stop ongoing calculations. If specific indicators are provided,
  /// only those studies will be removed; otherwise, all studies will be cleaned up.
  ///
  /// - Parameters:
  ///   - indicators: An optional array of `Indicator` objects specifying which studies to remove.
  ///                 If `nil`, all studies will be removed.
  ///   - completion: An optional closure that is called when the provider has finished cleaning up.
  func removeStudies(
      for indicators: [Indicator]?,
      completion: (() -> Void)?
  )
}

QuoteOperationsDelegate​

If you need to handle Buy and Sell values, you should create your own class which will confirm QuoteOperationsDelegate protocol. Then you need to implement thees functions in your class:

public protocol QuoteOperationsDelegate: AnyObject {
  func buyButtonWasPressed(_ value: Double?)
  func sellButtonWasPressed(_ value: Double?)
}

Additional features​

Logo image​

You can provide your logo image to be presented on the chart screen. To do it you should initialise ChartViewController with two additional parameters:

  • logoImage - requires UIImage;
  • shouldShowLogo - requires Bool value to determine whether to show the logo or not.

uniqueIdentifier​

You can provide a uniqueIdentifier, and the DXChart framework will use it to handle this chart’s data separately, including mechanisms for dividing data such as drawings and indicator settings.

Example of initialise ChartScreen:​

import UIKit
import DXChart
class Handler: DXChart.QuoteOperationsDelegate {
  func buyButtonWasPressed(_ value: Double?) {
      debugPrint(">>> HANDLER BUY sender.title = (value ?? 0)")
  }
  func sellButtonWasPressed(_ value: Double?) {
      debugPrint(">>> HANDLER SELL sender.title = (value ?? 0)")
  }
}
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var window: UIWindow?
  private let quoteOperationsHandler = Handler()
  func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
      guard let windowScene = (scene as? UIWindowScene) else { return }
      self.window = UIWindow(windowScene: windowScene)
      directStartWithChart()
  }
  private func directStartWithChart() {
      // like an example
      let dataProvider = CustomDataProvider(
          quoteAddress: <#quoteAddress#>,
          ipfAddress: <#ipfAddress#>,
          instrument: DXChartApp.dataStorage.instrument
      )
      let chartScreenViewController = ChartScreen.makeScreen(
          dataProvider: dataProvider,
          delegate: quoteOperationsHandler,
          logoImage: nil,
          shouldShowLogo: false,
          shouldShowToolbar: true
      }
      window?.rootViewController = chartScreenViewController
      window?.makeKeyAndVisible()
  }
}